home *** CD-ROM | disk | FTP | other *** search
- API - Application Interface
- English ..... A-1
- Deutsch ..... A-2
- Français .... A-3
- A-1 English
- BASICS
-
- GoldED offers a message-based application interface (API). This interface may be
- used by third party applications to register with GoldED: after having
- registered by sending the API command to GoldED's ARexx port they will recieve
- notify messages from GoldED. Depending on these messages they can take
- approbiate actions (e.g. close their windows if GED is about to close its
- screen, indicating this by sending API_ACTION_HIDE messages to all registered
- clients).
-
- HOW TO RUN CLIENTS
-
- Clients are launched during startup of GoldED (use the API list of the config
- menu if you want to add or remove clients). The name of GoldED's port is passed
- as HOST=... argument. The client is expected to register with GED by sending the
- API command to this port, thus providing a port for notifys and requesting
- notify classes (clients may select a subset of the available notifys).
-
- Shortly after the API client has registered with GoldED it will recieve an
- API_ACTION_SHOW notify of the API_CLASS_SCREEN class (if the client has
- requested API_CLASS_SCREEN events), telling the client to open its windows. This
- notify (and any other notify) includes a variety of informations about the
- editor's current state (including text of current line, window dimensions and
- screen name).
-
- RESTRICTIONS
-
- After a client has registered with GoldED it has to be able to answer notifys
- immediately until the API_ACTION_DIE command is recieved (the user has to WAIT
- for your client to complete processing). To avoid deadlock problems, you may not
- wait for completion of ARexx requests sent to GED using WaitPort() (thus
- ignoring incoming API messages). Use Wait() instead.
-
-
- A-2 Deutsch
- Grundlagen
-
- GoldED bietet externen Programmen mit dem API-Interface eine Möglichkeit, sich
- in die internen Abläufe des Editors einzuklinken. Ein Programm, das dieses
- Interface benutzt, wird im folgenden als Client bezeichnet. Das API-Interface
- baut wie auch ARexx auf Messages auf. Im Gegensatz zu ARexx geht die Richtung
- des Informationsflusses aber primär von GoldED zu den externen Programmen: der
- Ablauf wird durch den Editor gesteuert. Grundsätzlich kann man sich Clients wie
- Unterprogramme des Editors vorstellen: sie werden vom Editor "aktiviert",
- übernehmen die Ausführung und geben i.d.R. ein Ergebnis zurück. Die
- Client-Einbindung erfolgt, indem sich dieser bei GoldED mit dem ARexxBefehl API
- anmeldet. Dabei hat er mitzuteilen, in welchen Situationen er "aufgerufen"
- werden möchte und an welchem Port GoldED die entsprechende Nachricht hinterlegen
- soll. Tritt eine der ausgewählten Situationen auf, schickt GoldED an den
- angegebenen Port eine Message (Notify), die nähere Informationen (vgl. golded.h)
- enthält. Der Client wird diese Nachricht untersuchen, geeignete Aktionen
- durchführen und dann die Nachricht beantworten. Erst mit der Beantwortung fährt
- GoldED in seinem Programmablauf fort. Die Art der Antwort kann den weiteren
- Programmablauf beeinflussen.
-
- Wie werden Clients gestartet ?
-
- Benutzen Sie den API-Requester, um Clients auszuwählen. Jedes dort eingetragene
- Programm wird im Zuge des Editor-Startups aufgerufen. Der Name des ARexx-Ports
- von GED wird dem Client als (letztes) Argument HOST=... übergeben. Der Client
- bekommt so die Möglichkeit, sich über ARexx beim Editor anzumelden. Mit dem
- API-Kommando teilt er dem Editor mit, in welchen Situationen er informiert
- werden soll und an welchen Message-Port die Informationen verschickt werden
- sollen. Kurz nachdem sich der Client angemeldet hat, erhält er von GoldED eine
- erste API_ACTION_SHOW-Benachrichtigung (sofern der Client Informationen der
- API_CLASS_SCREEN angefordert hat): dies ist sein Signal, die eigenen Fenster
- (sofern vorgesehen) zu öffnen. Dazu benötigte Informationen wie der zu
- benutzende Screen kann er der Benachrichtigung entnehmen.
-
- Einschränkungen
-
- Nachdem sich ein Client über den API-Befehl erfolgreich beim Editor angemeldet
- hat, muss er in der Lage sein, eingehende Nachrichten unverzüglich zu
- bearbeiten, bis er eine API_ACTION_DIE-Benachrichtigung erhält. Wenn GoldED auf
- einen Client wartet, dann wartet auch der Anwender/die Anwenderin. Um
- DeadLock-Probleme zu vermeiden, darf niemals per WaitPort() auf abgesandte
- ARexx-Requests gewartet werden (GED könnte auf eine API-Reaktion des Clients
- warten, der Client wartet auf GoldED: das System ist blockiert). Verwenden Sie
- ersatzweise Wait().
-
- A-3 Français
-
- FONDEMENTS
-
- GoldED propose un interface application (API), basé sur les messages. Cet
- interface peut être utilisée par des applications pour s'enregistrer à GoldED:
- après s'être enregistrées en envoyant la commande API au port ARexx de GoldED,
- celles-ci recevront les messages de notification de GoldED. Selon ces messages,
- ces applications peuvent alors accomplir les actions appropriées (par exemple
- fermer leurs fenêtres si GED va fermer son écran, indiquant cela en envoyant les
- messages API_ACTION_HIDE à tous ses clients enregistrés).
-
- COMMENT DEMARRER DES CLIENTS
-
- Les clients sont lancés lors du démarrage de GoldED (utilisez la liste API du
- menu Config si vous voulez ajouter ou retirer des clients). Le nom du port de
- GoldED est passé comme argument <HOST=...>. Le client doit s'enregistrer à GED
- en envoyant la commande API à ce port, fournir en plus un port pour les
- notifications et demander les classes de notifications (les clients peuvent
- sélectionner une partie des notifications disponibles).
-
- Dès que le client API a été enregistré à GoldED, celui-ci reçoit une
- notification API_ACTION_SHOW de la classe API_CLASS_SCREEN (si le client a
- demandé les événements API_CLASS_SCREEN), lui disant d'ouvrir ses fenêtres.
- Cette notification (et toutes les autres notifications) inclut une quantité
- d'informations sur l'état actuel de l'éditeur (incluant le texte sur la ligne
- actuelle, les dimensions de la fenêtre et le nom de l'écran).
-
- RESTRICTIONS
-
- Dès qu'un client a été enregistré à GoldED, celui-ci doit être capable de
- répondre immédiatement aux notifications jusqu'à ce que la commande
- API_ACTION_DIE soit reçue (l'utilisateur devra ATTENDRE la fin du traitement par
- le client). Pour éviter des problèmes de temps mort (deadlock), vous ne devez
- pas attendre la fin des requêtes ARexx envoyées à GED en utilisant WaitPort()
- (en ignorant en plus les messages API arrivants). Utilisez Wait() à la place.
-